Improve docs

svn path=/trunk/; revision=20929

diff --git a/ChangeLog b/ChangeLog
index 3ed27ba520d08fbe5d23781a97ff634b72cf512f..552add2bf00c6d4307b9f6b34e95e3f72fbcfba4 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2008-08-02  Matthias Clasen  <mclasen@redhat.com>
+
+       * gdk/gdkapplaunchcontext.c: Improve the docs
+
 2008-08-01  Claudio Saavedra  <csaavedra@igalia.com>
 
        Bug 545931 – small documentation typos

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index f4cb42b2e2555af2b51c455f007c792d4d89c539..1d76720d9485e6b2312624b7b3355e72376c7368 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+2008-08-02  Matthias Clasen  <mclasen@redhat.com>
+
+       * gdk/tmpl/gdkapplaunchcontext.sgml: Add an introduction
+       with an example.
+
 2008-07-31  Matthias Clasen  <mclasen@redhat.com>
 
        * gdk/gdk-sections.txt: Add new api

diff --git a/docs/reference/gdk/tmpl/gdkapplaunchcontext.sgml b/docs/reference/gdk/tmpl/gdkapplaunchcontext.sgml
new file mode 100644 (file)
index 0000000..b1d4403
--- /dev/null
+++ b/docs/reference/gdk/tmpl/gdkapplaunchcontext.sgml
@@ -0,0 +1,106 @@
+<!-- ##### SECTION Title ##### -->
+Application launching
+
+<!-- ##### SECTION Short_Description ##### -->
+startup notification for applications
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+GdkAppLaunchContext is an implementation of #GAppLaunchContext that
+handles launching an application in a graphical context. It provides
+startup notification and allows to launch applications on a specific
+screen or workspace.
+</para>
+<example>
+<title>Launching an application</title>
+<programlisting>
+GdkAppLaunchContext *context;
+
+context = gdk_app_launch_context_new (<!-- -->);
+
+gdk_app_launch_context_set_screen (my_screen);
+gdk_app_launch_context_set_timestamp (event-&gt;time);
+
+if (!g_app_info_launch_default_for_uri ("http://www.gtk.org", context, &amp;error))
+  g_warning ("Launching failed: %s\n", error-&gt;message);
+
+g_object_unref (context);
+</programlisting>
+</example>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### TYPEDEF GdkAppLaunchContext ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_new ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_display ##### -->
+<para>
+
+</para>
+
+@context: 
+@display: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_screen ##### -->
+<para>
+
+</para>
+
+@context: 
+@screen: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_desktop ##### -->
+<para>
+
+</para>
+
+@context: 
+@desktop: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_timestamp ##### -->
+<para>
+
+</para>
+
+@context: 
+@timestamp: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_icon ##### -->
+<para>
+
+</para>
+
+@context: 
+@icon: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_icon_name ##### -->
+<para>
+
+</para>
+
+@context: 
+@icon_name: 
+
+

diff --git a/gdk/gdkapplaunchcontext.c b/gdk/gdkapplaunchcontext.c
index 04c83b5eb1a71e489fdcdedf0cf8a17299f9b5a9..15a013b768a780ba6f066fe97b0c91414b6155bb 100644 (file)
--- a/gdk/gdkapplaunchcontext.c
+++ b/gdk/gdkapplaunchcontext.c
@@ -134,7 +134,10 @@ gdk_app_launch_context_set_display (GdkAppLaunchContext *context,
  *
  * Sets the screen on which applications will be launched when
  * using this context. See also gdk_app_launch_context_set_display().
+ *
  * If both @screen and @display are set, the @screen takes priority.
+ * If neither @screen or @display are set, the default screen and
+ * display are used.
  *
  * Since: 2.14
  */
@@ -163,6 +166,10 @@ gdk_app_launch_context_set_screen (GdkAppLaunchContext *context,
  * <ulink url="http://www.freedesktop.org/Standards/wm-spec">Extended 
  * Window Manager Hints</ulink>. 
  *
+ * When the workspace is not specified or @desktop is set to -1, 
+ * it is up to the window manager to pick one, typically it will
+ * be the current workspace.
+ *
  * Since: 2.14
  */
 void
@@ -178,7 +185,12 @@ gdk_app_launch_context_set_desktop (GdkAppLaunchContext *context,
  * @timestamp: a timestamp
  *
  * Sets the timestamp of @context. The timestamp should ideally
- * be taken from the event that triggered the launch.
+ * be taken from the event that triggered the launch. 
+ *
+ * Window managers can use this information to avoid moving the
+ * focus to the newly launched application when the user is busy
+ * typing in another window. This is also known as 'focus stealing
+ * prevention'.
  *
  * Since: 2.14
  */
@@ -218,11 +230,14 @@ gdk_app_launch_context_set_icon (GdkAppLaunchContext *context,
  * @context: a #GdkAppLaunchContext
  * @icon_name: an icon name, or %NULL
  *
- * Sets the icon for applications that are launched with this
- * context. The @icon_name will be interpreted in the same way 
- * as the Icon field in desktop files. 
- * See also gdk_app_launch_context_set_icon(). If both @icon 
- * and @icon_name are set, the @icon_name takes priority.
+ * Sets the icon for applications that are launched with this context. 
+ * The @icon_name will be interpreted in the same way as the Icon field 
+ * in desktop files. See also gdk_app_launch_context_set_icon(). 
+ *
+ * If both @icon and @icon_name are set, the @icon_name takes priority.
+ * If neither @icon or @icon_name is set, the icon is taken from either 
+ * the file that is passed to launched application or from the #GAppInfo 
+ * for the launched application itself.
  * 
  * Since: 2.14
  */